一句話破題

在寫任何一行 Laravel 程式碼之前，你需要一台裝好對版本 PHP、對版本 Composer 的電腦——這句話聽起來理所當然，但「對版本」三個字在 Laravel 13 時代有了新的答案：最低要求是 PHP 8.3。今天我們把環境從零建起來，同時也讓你了解 Laravel 每個大版本號背後的 PHP 版本需求邏輯，之後不管你接手什麼專案，都能一眼判斷「這個專案能不能升級」。

背景：為什麼版本對應這麼重要

Laravel 官方大致上每年會發布一個大版本（主要在第一季），每個大版本都會綁定一個 PHP 最低需求版本，而且會同時支援一個 PHP 版本區間。這件事直接關係到你能不能升級框架、以及你的正式環境主機該裝哪個 PHP：

看這張表可以抓到幾個實用結論：

• Laravel 對每個大版本提供 18 個月的 bug 修正、2 年的安全性修正。如果你手上的專案還是 Laravel 10，安全性修正已經在 2025-02-04 到期，代表這個版本已經完全沒有官方支援了，升級不是「要不要」的問題，是「該排進計畫」的問題。
• Laravel 13 的 PHP 支援區間是 8.3 到 8.5，這代表要開新專案直接裝 PHP 8.3 以上就對了；過去常見的 PHP 8.1、8.2 環境放到 Laravel 13 已經不能用。

這張表背後的邏輯：為什麼版本支援區間會「重疊」

仔細看這張表你會發現一個有趣的現象：Laravel 11 支援 PHP 8.2-8.4，Laravel 12 也支援 8.2 起跳，Laravel 13 才把下限拉到 8.3。這不是隨便訂的，背後反映的是 Laravel 團隊的一個明確政策：每個 Laravel 大版本的 PHP 最低需求，通常會跟進當時「還在積極維護」的最舊 PHP 版本。PHP 本身也有自己的版本生命週期（每個 PHP 版本大約 2 年 active support + 1 年 security-only），Laravel 會盡量避免要求一個已經停止安全更新的 PHP 版本。

這對你實際的決策有一個具體含義：不要只看「Laravel 13 最低要求 8.3」就覺得裝 8.3 剛好卡底線。PHP 8.3 本身也有自己的到期時間，如果你現在開一個要長期維運的專案，裝 Laravel 13 支援範圍內的較新版本（例如 8.4 或 8.5），能讓你在同一個 Laravel 大版本的生命週期裡，少一次「PHP 版本快過期了要不要順便升級」的額外決策。blog-app 這系列統一用 PHP 8.3，是為了跟 Laravel 13 的最低需求對齊、方便示範，你自己的專案如果條件允許，選區間內較新的版本會更划算。

安裝 PHP

PHP 本身的安裝方式不會因為 Laravel 版本而改變，只是版本號要換成 8.3 以上。Windows 使用者可以照著做：

1. 前往 windows.php.net/download 下載最新的 PHP 8.3 或以上版本；如果需要特定小版本（例如接手舊專案），可以到 archives 找。
2. 下載時注意兩個選擇：
   • x86 / x64：選 x64 即可，能相容 32/64 位元系統，現在幾乎不會有人選 x86。
   • NTS（Non Thread Safe）/ TS（Thread Safe）：如果你搭配 Nginx（透過 PHP-FPM），選 NTS；如果搭配 Apache 的 mod_php，選 TS。多數現代開發環境（含 Laragon、Docker）預設用 Nginx/PHP-FPM 組合，選 NTS 準沒錯。
3. 解壓縮到一個固定路徑，例如 C:\Program Files\php83。
4. 到「環境變數」設定裡，把這個路徑加進 Path。
5. 開一個新的 cmd，輸入 php -v 確認版本正確、php -r "echo 'hello world';" 確認能執行程式碼。

macOS / Linux 使用者建議直接用 Homebrew（brew install php@8.3）或系統套件管理員安裝，不建議手動編譯。

php.ini：安裝完之後容易被忽略的設定檔

裝好 PHP 之後，多數人會直接跳去裝 Composer、建專案，但 php.ini 這個設定檔值得花兩分鐘認識一下，因為它會直接影響你開發時的體驗：

; php.ini 幾個開發階段常會調整的設定
memory_limit = 512M          ; 預設 128M 對 Composer 安裝大型套件常常不夠
upload_max_filesize = 20M    ; 預設 2M，測試檔案上傳功能時很容易卡在這裡
post_max_size = 20M          ; 要跟 upload_max_filesize 搭配調整，且通常要略大於它
max_execution_time = 30      ; 開發階段偶爾會遇到需要延長的情境（例如跑大量 Seeder）
display_errors = On          ; 開發環境建議開啟，正式環境務必關閉（Day 6 會深入這個主題）

php --ini 指令可以告訴你目前實際載入的是哪個 php.ini 檔案路徑——這個指令在踩雷排查時比想像中好用，因為同一台電腦如果裝過多個 PHP 版本，很容易改錯設定檔而不自知。

多版本 PHP 並存，現在還需要嗎？

「同一台電腦裝多個 PHP 版本，把 exe 改名成 php83.exe、php74.exe 分開呼叫」這個土法煉鋼技巧概念上沒過時，但老實說，現在更推薦用 Docker 或 Laragon 這類工具處理多版本需求，原因很直接：

• 手動改檔名的方式，每個專案都要記得自己該用哪個 phpXX.exe，容易搞混。
• Docker 容器天生就是「每個專案一個獨立環境」，版本問題自然被隔離掉。
• Laragon 內建版本切換 UI，點兩下就能切換目前使用的 PHP 版本，不用碰環境變數。

除了這兩個之外，如果你是 macOS/Linux 使用者，另外有兩個社群常見的版本管理工具值得認識：

這系列不特別展開這兩個工具的安裝細節，因為多數讀者的情境用 Docker 或 Laragon 就已經夠用；提到它們純粹是讓你知道「如果哪天真的需要更細緻的版本控制，還有這些選項」。

Day 3 會完整介紹 Laragon 和 Docker 的用法，如果你只是想快速跑起一個 Laravel 13 專案試試看，直接跳到 Day 3 用 Laragon 或 Sail 也完全沒問題——手動安裝 PHP 這套流程比較適合想搞懂底層運作原理、或是要佈署到自己管理的伺服器時使用。

安裝 Composer

Composer 是 PHP 的套件管理工具，Laravel 專案的相依套件（包含框架本身）都是透過它安裝的。這部分同樣沒有版本相關的變動：

1. Windows 使用者前往 getcomposer.org/download 下載安裝精靈，安裝時會要求指定要綁定的 PHP 路徑，選你剛剛裝好的 PHP 執行檔即可。
2. macOS / Linux 使用者可以用官方提供的安裝指令碼，或透過 Homebrew（brew install composer）安裝。
3. 安裝完成後開新的終端機，輸入 composer -v 確認安裝成功。

composer.json 的版本約束語法，值得花時間搞懂

安裝完 Composer 之後，接下來 30 天你會頻繁跟 composer.json 打交道，這裡先把版本約束的語法講清楚，省得之後每次看到都要重新猜一次：

{
    "require": {
        "php": "^8.3",
        "laravel/framework": "^13.0",
        "guzzlehttp/guzzle": "~7.8.0",
        "some/package": "7.8.*",
        "another/package": ">=2.0 <3.0"
    }
}

實務上 ^（插入號）是目前最常見、也是 Laravel 官方套件預設使用的寫法，因為它在「允許拿到修正與新功能」跟「避免不小心裝到有破壞性變動的大版本」之間取得了不錯的平衡。~（波浪號）則更保守，適合你明確知道套件在小版號更新時可能有破壞性變動的情況。

Global 與 Project 兩種安裝方式的差異

composer global require xxx 跟 composer require xxx（不加 global）是兩件不同的事，混用很容易讓人搞不清楚一個套件到底裝在哪：

• composer require（專案層級）：裝進目前資料夾的 vendor/ 目錄，記錄進這個專案的 composer.json，只有這個專案能用。Laravel 的框架本身、以及幾乎所有你在專案裡實際 use 的套件，都是用這種方式安裝。
• composer global require（全域層級）：裝進你使用者帳號底下的全域 Composer 目錄（不屬於任何專案），通常用來安裝「CLI 工具」而不是「程式庫」，例如 laravel/installer（Day 4 會用到）就是全域安裝的典型案例——你希望在任何目錄下都能打 laravel new，而不是每個專案各自裝一份。

一個簡單的判斷原則：如果這個套件是要在你的 PHP 程式碼裡 use 它、寫進 composer.json 的 require，用專案層級安裝；如果這個套件是一個你想在終端機直接呼叫的指令列工具，考慮全域安裝。

套件本身也有 PHP 版本要求，別忽略

這裡有個很容易被忽略的重點：Laravel 框架本身有 PHP 版本要求，但你安裝的第三方套件也各自有自己的 PHP 版本要求。舉例來說，一個處理 Excel 匯出的套件 maatwebsite/excel，它的 composer.json 裡可能寫著：

"require": {
    "php": "^7.0||^8.0"
}

^7.0||^8.0 的意思是「7.0.0 以上但不到 8.0.0 的版本，或者 8.0.0 以上（不限上限，除非另有其他約束限制）的版本都可以」，|| 是「或」的意思。如果你的 Laravel 專案跑在 PHP 8.3，而某個套件的 require 寫死 "php": "^7.4"（不含 ||^8.0），Composer 會直接拒絕安裝並跳出版本衝突錯誤。挑第三方套件時，先看一眼它的 PHP 版本要求，是升級評估中很容易漏掉但很重要的一步。

實務上判斷一個套件「值不值得信賴」，除了看 PHP 版本相容性，還可以快速看幾個指標：

• composer.json 裡的 require 有沒有寫 Laravel 版本約束（如果是 Laravel 專用套件）：如果只支援到 laravel/framework: ^10.0，代表這個套件可能已經沒在積極維護，跟 Laravel 13 專案搭配前要先確認相容性。
• 最近一次 release 的時間：Packagist（packagist.org）上每個套件頁面都會顯示版本發布時間，超過一兩年沒更新的套件，遇到新版 PHP/Laravel 的相容性問題時，可能得不到及時修正。
• 是否有替代方案已經被官方收編：Day 8 會提到的 once() 就是一個例子——原本社群套件 spatie/once 做的事，Laravel 11 直接內建了。裝套件前先確認框架本身是否已經有等效功能，能省下一個長期維護的相依。

建立一個測試專案，確認環境真的可用

環境都裝好之後，最快的驗收方式就是實際建一個專案跑跑看。建立新專案有兩種常見方式：

# 方式一：透過 composer 直接建立，產生最陽春的空白骨架
composer create-project laravel/laravel hello-laravel

# 方式二：透過 Laravel 官方 installer（需先全域安裝 installer）
composer global require laravel/installer
laravel new hello-laravel

兩種方式都會產生一個含最新版 Laravel（目前就是 13.x）骨架的資料夾。建立完成後，進到專案資料夾試著啟動內建伺服器：

cd hello-laravel
php artisan serve

瀏覽器打開 http://127.0.0.1:8000，看到 Laravel 的歡迎頁面就代表環境正確無誤。

注意這裡刻意把專案取名叫 hello-laravel 而不是 blog-app——今天建的這個只是用來驗收環境的拋棄式專案，確認跑得起來之後可以直接刪掉。這系列真正要一路蓋到 Day 30 的 blog-app，會在 Day 4 用官方 installer 搭配 Starter Kit 正式建立，因為那時候還要在互動式問答裡選前端方案跟認證設定，跟今天這個純粹「確認 PHP/Composer 沒裝壞」的空白專案不是同一件事。

先把這個約定講清楚：從 Day 4 起，所有範例都會用 blog-app 這個專案名稱，展示網域是一個部落格系統（Post 文章、User 使用者），後面每一天都會延續這個設定，不會中途換成別的範例網域。

確認環境正確的幾個實用指令

除了看到歡迎頁面，這裡再補幾個開發過程中會反覆用到、用來確認環境狀態的指令，先認識起來比之後遇到問題才臨時查要有效率：

php artisan about              # 一次列出目前應用程式的完整環境資訊（PHP 版本、Laravel 版本、快取狀態、驅動設定等）
php artisan --version          # 只看 Laravel 版本號
php -m                         # 列出目前 PHP 載入了哪些擴充套件
composer show laravel/framework   # 查看目前專案安裝的 Laravel 確切版本與相依關係

php artisan about 是 Laravel 11 起變得特別實用的一個指令——它把過去要分別執行好幾個指令才能拼湊出的環境資訊（版本、環境變數狀態、快取狀態、Session/Queue/Cache 驅動）整合成一份清單，之後如果你要回報 bug、或請同事協助排查環境問題，直接貼這個指令的輸出，往往比口頭描述「我的環境是這樣那樣」清楚得多。

常見錯誤與踩雷點

• 裝了 PHP 但 php -v 顯示版本不對：通常是環境變數 Path 裡同時存在多個 PHP 路徑，系統抓到的是排序在前面的那個舊版本。檢查 Path 清單，把新版本路徑移到最前面，或乾脆刪掉舊路徑。用 where php（Windows）或 which -a php（macOS/Linux）可以列出系統實際掃到的所有 php 執行檔位置，快速定位問題出在哪一個。
• Composer 安裝套件時噴出 PHP 版本衝突訊息：先看清楚訊息裡是「你的 PHP 版本」還是「Laravel 版本」跟套件衝突，再去對照套件的 composer.json 判斷是升級套件版本還是換一個套件。Composer 的錯誤訊息通常會列出完整的相依鏈（哪個套件要求了哪個版本），耐心往上追一層一層看，通常能找到真正衝突的源頭。
• 忘記 PHP 擴充套件（extension）沒開：Laravel 常用到 fileinfo、mbstring、openssl、pdo_mysql、pdo_sqlite 這幾個擴充套件，如果是手動裝的 PHP，記得打開 php.ini 把對應的 extension= 那行前面的分號 ; 拿掉。用 Laragon 或 Docker 的話這些預設都已經開好，不用擔心這點。
• composer create-project 執行到一半卡住或超時：通常是網路連線到 Packagist 或某個套件的 GitHub repo 不穩定，可以加上 --prefer-dist 參數（優先下載打包好的壓縮檔而非 git clone，速度通常更快），或檢查是否需要透過公司網路的 proxy 設定 composer config -g proxy。
• memory_limit 不夠導致 Composer 安裝失敗，噴出 Allowed memory size exhausted：這在安裝相依關係複雜的大型套件時偶爾會遇到，前面提過的 memory_limit = 512M 設定通常能解決；也可以在指令前臨時加大限制：php -d memory_limit=1G $(which composer) require xxx。
• Windows 使用者路徑裡有中文或空白，導致某些套件安裝報錯：極少數套件的建置腳本對路徑編碼處理不夠嚴謹，如果專案路徑剛好在使用者名稱含中文的帳號底下，遇到奇怪的安裝錯誤時可以先排除這個可能性，最保險的做法是把專案放在純英數字路徑下（例如 C:\projects\blog-app）。

小結

Laravel 13 把最低 PHP 版本要求拉到 8.3，這是這次環境建置最重要的變化；安裝流程本身（下載 PHP、設環境變數、裝 Composer）跟三年前沒有本質上的差異。今天我們用一個拋棄式的 hello-laravel 專案驗收了環境，並認識了 composer.json 版本約束語法、php artisan about 這類實用的環境檢查工具，這些是接下來每天都會反覆用到的基本功。真正貫穿 30 天的示範專案 blog-app，Day 4 會正式建立。

磨刀不誤砍柴工 — 中國諺語

明日預告

Day 3 進入開發工具的世界：Laragon、Docker、Laravel Sail 三種本機開發環境該怎麼選，以及讓你少走很多冤枉路的 VS Code 擴充套件推薦。